~ chicken-core (master) /manual/Module (chicken tcp)
Trap1[[tags: manual]]2[[toc:]]34== Module (chicken tcp)56This module provides basic facilities for communicating over TCP7sockets.89All errors related to failing network operations will raise a condition10of kind {{(exn i/o net)}}.111213=== tcp-listen1415<procedure>(tcp-listen TCPPORT [BACKLOG [HOST]])</procedure>1617Creates and returns a TCP listener object that listens for connections on {{TCPPORT}}, which18should be an exact integer. {{BACKLOG}} specifies the number of maximally pending19connections (and defaults to 100). If the optional argument {{HOST}} is given and not20{{#f}}, then only incoming connections for the given host (or IP) are accepted.212223=== tcp-listener?2425<procedure>(tcp-listener? X)</procedure>2627Returns {{#t}} if {{X}} is a TCP listener object, or {{#f}} otherwise.282930=== tcp-close3132<procedure>(tcp-close LISTENER)</procedure>3334Reclaims any resources associated with {{LISTENER}}.353637=== tcp-accept3839<procedure>(tcp-accept LISTENER [ENCODING])</procedure>4041Waits until a connection is established on the port on which42{{LISTENER}} is listening and returns two values: an input- and43output-port that can be used to communicate with the remote44process. The current value of {{tcp-accept-timeout}} is used to45determine the maximal number of milliseconds (if any) to wait46until a connection is established. When a client connects any47read- and write-operations on the returned ports will use the48current values (at the time of the connection) of {{tcp-read-timeout}}49and {{tcp-write-timeout}}, respectively, to determine the maximal50number of milliseconds to wait for input/output before a timeout51error is signalled.5253{{ENCODING}} should be a symbol specifying the encoding to be54used for I/O operations, the default is {{utf-8}}. The encodings for55the returned in and output ports can be subsequently changed by56using the {{port-encoding}} setter.5758Note: this operation and any I/O on the ports returned will not block59other running threads.606162=== tcp-accept-ready?6364<procedure>(tcp-accept-ready? LISTENER)</procedure>6566Returns {{#t}} if there are any connections pending on {{LISTENER}}, or {{#f}}67otherwise.686970=== tcp-listener-port7172<procedure>(tcp-listener-port LISTENER)</procedure>7374Returns the port number assigned to {{LISTENER}} (If you pass {{0}} to {{tcp-listen}},75then the system will choose a port-number for you).7677=== tcp-listener-fileno7879<procedure>(tcp-listener-fileno LISTENER)</procedure>8081Returns the file-descriptor associated with {{LISTENER}}.828384=== tcp-connect8586<procedure>(tcp-connect HOSTNAME [TCPPORT ENCODING])</procedure>8788Establishes a client-side TCP connection to the machine with the name89{{HOSTNAME}} (a string) at {{TCPPORT}} (an exact integer) and returns90two values: an input- and output-port for communicating with the91remote process. The current value of {{tcp-connect-timeout}} is used92to determine the maximal number of milliseconds (if any) to wait until93the connection is established. When the connection takes place any94read- and write-operations on the returned ports will use the current95values (at the time of the call to {{tcp-connect}}) of {{tcp-read-timeout}} and96{{tcp-write-timeout}}, respectively, to determine the maximal number97of milliseconds to wait for input/output before a timeout error is98signalled.99100If the {{TCPPORT}} is omitted, the port is parsed from the {{HOSTNAME}} string. The format expected is {{HOSTNAME:PORT}}. The {{PORT}} can either be a string representation of an integer or a service name which is translated to an integer using the POSIX function [[http://www.opengroup.org/onlinepubs/009695399/functions/getservbyname.html|{{getservbyname}}]].101102{{ENCODING}} should be a symbol specifying the encoding to be103used for I/O operations, the default is {{utf-8}}. The encodings for104the returned in and output ports can be subsequently changed by105using the {{port-encoding}} setter.106107Note: any I/O on the ports returned will not block other running threads.108109110=== tcp-addresses111112<procedure>(tcp-addresses PORT)</procedure>113114Returns two values for the input- or output-port {{PORT}} (which should be a port returned115by either {{tcp-accept}} or {{tcp-connect}}): the IP address of the local and the remote116machine that are connected over the socket associated with {{PORT}}. The returned addresses117are strings in {{XXX.XXX.XXX.XXX}} notation.118119120=== tcp-port-numbers121122<procedure>(tcp-port-numbers PORT)</procedure>123124Returns two values for the input- or output-port {{PORT}} (which should be a port returned125by either {{tcp-accept}} or {{tcp-connect}}): the TCP port numbers of the local and the remote126machine that are connected over the socket associated with {{PORT}}.127128129=== tcp-abandon-port130131<procedure>(tcp-abandon-port PORT)</procedure>132133Marks the socket port {{PORT}} as abandoned. This is mainly useful to close down a port134without breaking the connection.135136137=== tcp-buffer-size138139<parameter>tcp-buffer-size</parameter>140141Sets the size of the output buffer. By default no output-buffering for142TCP output is done, but to improve performance by minimizing the143number of TCP packets, buffering may be turned on by setting this144parameter to an exact integer greater zero. A buffer size of zero or {{#f}}145turns buffering off. The setting of this parameter takes effect at the time146when the I/O ports for a particular socket are created, i.e. when {{tcp-connect}}147or {{tcp-accept}} is called.148149Note that since output is not immediately written to the associated socket, you150may need to call {{flush-output}}, once you want the output to be transmitted.151Closing the output port will flush automatically.152153=== tcp-read-timeout154155<parameter>tcp-read-timeout</parameter>156157Determines the timeout for TCP read operations in milliseconds. A timeout of158{{#f}} disables timeout checking. The default read timeout is 60000, i.e.1591 minute.160If timeout occurs while reading, a condition object of kinds {{(exn i/o net timeout)}}161is thrown.162163=== tcp-write-timeout164165<parameter>tcp-write-timeout</parameter>166167Determines the timeout for TCP write operations in milliseconds. A timeout of168{{#f}} disables timeout checking. The default write timeout is 60000, i.e.1691 minute.170If timeout occurs while writing, a condition object of kinds {{(exn i/o net timeout)}}171is thrown.172173=== tcp-connect-timeout174175<parameter>tcp-connect-timeout</parameter>176177Determines the timeout for {{tcp-connect}} operations in milliseconds. A timeout of178{{#f}} disables timeout checking and is the default.179If timeout occurs while trying to connect, a condition object of kinds {{(exn i/o net timeout)}}180is thrown.181182183=== tcp-accept-timeout184185<parameter>tcp-accept-timeout</parameter>186187Determines the timeout for {{tcp-accept}} operations in milliseconds. A timeout of188{{#f}} disables timeout checking and is the default.189If timeout occurs while waiting for connections, a condition object of kinds {{(exn i/o net timeout)}}190is thrown.191192193=== Example194195A very simple example follows. Say we have the two files {{client.scm}}196and {{server.scm}}:197198<enscript highlight=scheme>199; client.scm200(import (chicken io) (chicken tcp))201(define-values (i o) (tcp-connect "localhost" 4242))202(write-line "Good Bye!" o)203(print (read-line i))204</enscript>205206<enscript highlight=scheme>207; server.scm208(import (chicken io) (chicken tcp))209(define l (tcp-listen 4242))210(define-values (i o) (tcp-accept l))211(write-line "Hello!" o)212(print (read-line i))213(close-input-port i)214(close-output-port o)215</enscript>216217 % csc server.scm218 % csc client.scm219 % ./server &220 % ./client221 Good Bye!222 Hello!223224---225Previous: [[Module (chicken syntax)]]226227Next: [[Module (chicken time)]]